docs(factories): add concise overview and workflow - #516
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR adds the Warp Factories documentation surface and reorganizes related platform/reference navigation while updating rename-sensitive terminology variables. The new factory overview/workflow content is substantial, but the PR still exposes placeholder pages and includes broken internal links to factory depth pages that are not present in the diff.
Concerns
- The Factories sidebar publishes four pages whose bodies are still visible
[STUB ...]placeholders. - The Factories overview and workflow pages link to factory depth pages such as
factory-agents,factory-as-code,factory-mcp, andmeasure-and-improvethat are not added by this PR, which will leave users on 404s.
Found: 2 critical, 1 important, 0 suggestions
Verdict
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| { slug: 'factories/quickstart', label: 'Quickstart' }, | ||
| { slug: 'factories/how-factories-work', label: 'How Factories work' }, | ||
| { slug: 'factories/configure-your-factory', label: 'Configure your Factory' }, | ||
| { slug: 'factories/connect-your-factory', label: 'Connect your Factory' }, | ||
| { slug: 'factories/infrastructure-and-security', label: 'Infrastructure & security' }, |
There was a problem hiding this comment.
[STUB ...] placeholders (quickstart, configure-your-factory, connect-your-factory, and infrastructure-and-security); either replace the stubs with launch-ready content or keep them out of navigation until the content exists.
| * [**Factory agents**](./factory-agents) - Understand the default agent roles and how they collaborate. | ||
| * [**Configure your factory**](./configure-your-factory) - Configure agents, automations, integrations, and execution resources. | ||
| * [**Factory definitions as code**](./factory-as-code) - Define repositories, agents, automations, runners, skills, and MCP servers. | ||
| * [**Connect your factory**](./connect-your-factory) - Route work from engineering tools and coding agents. | ||
| * [**Factory MCP**](./factory-mcp) - Exchange work and context with a factory from an MCP client. | ||
| * [**Measure and improve**](./measure-and-improve) - Evaluate runs, compare configurations, and refine the factory. |
There was a problem hiding this comment.
🚨 [CRITICAL] These links include ./factory-agents, ./factory-as-code, ./factory-mcp, and ./measure-and-improve, but those pages are not added in this diff, so the overview will send readers to 404s; add the target pages or remove the links before publishing.
| 4. Teams identify a concrete change to the factory. | ||
| 5. The updated definition governs later work items. | ||
|
|
||
| The [factory definitions as code](./factory-as-code) page explains the declarative model. See [connect your factory](./connect-your-factory) for intake paths, [Factory MCP](./factory-mcp) for agent-to-factory exchange, and [measure and improve](./measure-and-improve) for the outer loop. |
There was a problem hiding this comment.
🚨 [CRITICAL] This related-links sentence points to missing ./factory-as-code, ./factory-mcp, and ./measure-and-improve pages, so users following the workflow page will hit 404s; link only to pages that exist in this PR or add the missing pages.
1fecf37 to
f84bace
Compare
hongyi-chen
changed the title
f84bace to
7d371d2
Compare
7d371d2 to
07008b2
Compare
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the Factory stubs with concise overview and workflow documentation, plus a platform overview cross-link. The new Factory pages are structured and scoped appropriately, but one changed platform paragraph introduces an unimported MDX variable that will break the page build.
Concerns
src/content/docs/platform/overview.mdxnow referencesVARS.WARP_AUTOMATION_PLATFORMwithout adding the requiredimport { VARS } from '@data/vars';, so MDX compilation will fail unless the import is added or the text is made static.
Verdict
Found: 1 critical, 0 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| [Warp Factories](/factories/) give engineering teams open, flexible infrastructure for building and operating their own cloud software factories. A factory composes the primitives described on this page — triggers, tasks, environments, hosts, and integrations — into an automation loop around your development lifecycle. | ||
|
|
||
| Factories are in closed beta. See the [Factories](/factories/) tab for what a software factory is, how to configure and connect one, and how to apply. | ||
| [Warp Factories](/factories/) assembles the {VARS.WARP_AUTOMATION_PLATFORM} primitives described on this page into persistent, multi-agent software development workflows. A factory coordinates specialized cloud agents around work items as they move through stages such as triage, specification, implementation, review, and verification. |
There was a problem hiding this comment.
🚨 [CRITICAL] This page does not import VARS, so this new MDX expression will fail to compile; add import { VARS } from '@data/vars'; at the top of the file or keep this text static.
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces Factories stub content with two concise conceptual pages and updates the platform overview to point at the new Factories workflow. The new Factories pages are generally structured and scoped appropriately, but one changed platform overview line appears to introduce an unresolved MDX variable reference that can break the docs build.
Concerns
src/content/docs/platform/overview.mdxnow usesVARS.WARP_AUTOMATION_PLATFORM, but the diff does not add the requiredVARSimport for that file. If the import is absent in the target branch, Astro/MDX rendering will fail.- No approved or repository spec context was provided, so no implementation-vs-spec drift findings were evaluated.
- No security-specific issues were found in the documentation changes beyond the build-blocking concern above.
Verdict
Found: 1 critical, 0 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| [Warp Factories](/factories/) give engineering teams open, flexible infrastructure for building and operating their own cloud software factories. A factory composes the primitives described on this page — triggers, tasks, environments, hosts, and integrations — into an automation loop around your development lifecycle. | ||
|
|
||
| Factories are in closed beta. See the [Factories](/factories/) tab for what a software factory is, how to configure and connect one, and how to apply. | ||
| [Warp Factories](/factories/) assembles the {VARS.WARP_AUTOMATION_PLATFORM} primitives described on this page into persistent, multi-agent software development workflows. A factory coordinates specialized cloud agents around work items as they move through stages such as triage, specification, implementation, review, and verification. |
There was a problem hiding this comment.
🚨 [CRITICAL] This file now references VARS, but the diff does not add import { VARS } from '@data/vars'; after the frontmatter; add that import or this MDX page can fail at build/render time.
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces the Factories stubs with concise overview and execution-model documentation, then updates the platform overview to point readers toward the new Factories section. The spec context file says no approved or repository spec context was found, and the supplemental security pass found no security findings.
Concerns
src/content/docs/platform/overview.mdxnow referencesVARSwithout importing it, which should fail MDX compilation until the import is added.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| [Warp Factories](/factories/) give engineering teams open, flexible infrastructure for building and operating their own cloud software factories. A factory composes the primitives described on this page — triggers, tasks, environments, hosts, and integrations — into an automation loop around your development lifecycle. | ||
|
|
||
| Factories are in closed beta. See the [Factories](/factories/) tab for what a software factory is, how to configure and connect one, and how to apply. | ||
| [Warp Factories](/factories/) assembles the {VARS.WARP_AUTOMATION_PLATFORM} primitives described on this page into persistent, multi-agent software development workflows. A factory coordinates specialized cloud agents around work items as they move through stages such as triage, specification, implementation, review, and verification. |
There was a problem hiding this comment.
VARS, but this file only imports VideoEmbed, so MDX compilation will fail until import { VARS } from '@data/vars'; is added after the frontmatter.
There was a problem hiding this comment.
The required import { VARS } from '@data/vars'; is already present immediately after the frontmatter on the current head. npm run typecheck and the full 377-page build both pass. Retriggering review so this stale finding can be cleared.
|
/oz-review |
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
There was a problem hiding this comment.
Overview
This PR replaces Factories scaffolding with two concise conceptual pages and updates the platform overview to point readers at Factories. The docs content is mostly scoped and scannable, but one added MDX expression appears to be missing its import in the changed file.
Concerns
src/content/docs/platform/overview.mdxnow referencesVARS.WARP_AUTOMATION_PLATFORM, but the diff does not add theVARSimport in that file. This likely breaks the MDX build unless the import is added with the existing imports.- No approved spec context was supplied for this implementation PR, so there was no spec drift to evaluate.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| [Warp Factories](/factories/) give engineering teams open, flexible infrastructure for building and operating their own cloud software factories. A factory composes the primitives described on this page — triggers, tasks, environments, hosts, and integrations — into an automation loop around your development lifecycle. | ||
|
|
||
| Factories are in closed beta. See the [Factories](/factories/) tab for what a software factory is, how to configure and connect one, and how to apply. | ||
| [Warp Factories](/factories/) assembles the {VARS.WARP_AUTOMATION_PLATFORM} primitives described on this page into persistent, multi-agent software development workflows. A factory coordinates specialized cloud agents around work items as they move through stages such as triage, specification, implementation, review, and verification. |
There was a problem hiding this comment.
VARS.WARP_AUTOMATION_PLATFORM, but the diff does not import VARS; add import { VARS } from '@data/vars'; with the existing imports or the MDX build will fail.
07008b2 to
d35fdde
Compare
|
/oz-review |
|
This is your last |
- Move the stage diagram in how-factories-work.mdx into the Stages section with an introductory sentence, so it follows the prose that motivates it. - Rewrite the Stages bullet list as consistent complete sentences with explicit subjects (triage agent, specification agent, implementation agent, review agent). - Resolve Complete/Cancelled bolding ambiguity by relying on the bolded list term instead of re-bolding Cancelled as a UI element. - Clarify the Work items and agent runs section, removing the awkward semicolon construction and ambiguous "it" pronoun. - Retitle "Where humans decide" to "What humans decide" to match the section's content. - Rewrite several mid-sentence colon constructions across how-factories-work.mdx and index.mdx into direct, complete sentences, and link the first mention of Scorer evaluations. Co-Authored-By: Warp <agent@warp.dev>
- Confirm and keep singular verb agreement for Warp Factories (is/lets/ runs), consistent with the terminology glossary. - Restructure the Early Access note into complete sentences. - Replace the vague 'automation loop around software development' with a direct statement that a software factory automates the SDLC, and fix the resulting dangling 'that loop' reference. - Retitle 'Who Warp Factories is for' to 'Who benefits from Warp Factories' and 'What Warp Factories provides' to 'What you get with Warp Factories' for clearer, more value-oriented headers. - Replace vague 'fits' with a direct statement of who the product is designed for. - Clarify 'defaults' as 'default roles' and restate custom agents/automations as something a reader can add, not just a vague coverage gap. Co-Authored-By: Warp <agent@warp.dev>
Conflict: factories/index.mdx was a STUB here and is now fully written upstream (#516). Took the base version, same as the other factory pages. Review feedback, both points valid: 1. platform-determiner skipped all of frontmatter, leaving `description` unguarded. That is the field that becomes the meta description -- the text search engines and AI engines read before deciding whether to cite a page -- so it was the worst field to have uncovered. The check now tracks which frontmatter key it is inside and scans `description`, including folded `>-` blocks that continue across indented lines, while `title` and `sidebar.label` stay exempt because those are headline-style and correctly bare. Closing the gap surfaced no live defects: determiner count is still 0. So this is prevention rather than a fix, which is the honest read -- though the gap was real, and I hit its consequences earlier in this work when stale meta descriptions turned out to be invisible to every check I had. 2. Slack and Linear instructions had been given "the {platform}" by the article pass, in sentences describing who a teammate addresses. You do not assign a Linear issue to a platform or @-mention one in Slack. Fixed both flagged sites to name the handle, plus one the reviewer did not flag: the next line said the platform "will acknowledge the request", which is the same error -- an agent acknowledges, a platform does not. The reviewer's suggested text used @oz, correct when the review ran. Product confirmed @warp later the same day, so the intent is applied with the current handle. Verified: style_lint 1132, hardcoded-var 0, platform-determiner 0; determiner regression suite passes, including the new frontmatter cases. Co-Authored-By: Warp <agent@warp.dev>
… and cross-page seams (#557) * docs(factories): convert relative links to root-absolute on launch pages Relative links resolve against the page's trailing-slash URL at runtime (./x becomes /factories/<page>/x), so they 404 even though the file-based CI link checker passes. #550 swept the pages merged before it; the pages that landed after (#516 overview/how-it-works, #520 connect, #527 Linear) reintroduced the pattern. Converts all of them to the repo's root-absolute trailing-slash convention. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): fix cross-page seams left by the stacked launch PRs - Map the setup wizard's Code toggle to the Implement role (quickstart vs factory-agents used different names for the same role) - Map lifecycle stage names to the Activity view's UI names (Planning, Building), which how-factories-work never connected - Define a Factory MCP task as the factory's work item; the page used 'task' throughout without bridging to the term the rest of the section uses - Link connect-your-factory to the automation-filters page (#551 added the page after #520 merged, so the hub never referenced it) - Align 'cancelled' spelling on the Jira page with the rest of the section - Replace two 'cloud agent identity' usages with 'cloud agent' per the terminology glossary (platform/agents.mdx) Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp <agent@warp.dev>
2 participants
Summary
Condenses the Factories overview and workflow into two focused conceptual pages. The overview defines the product, audience, capabilities, product boundaries, and sole Early Access note. How it works keeps the foreman lifecycle, reversible stage model, human-policy boundary, work-item/run distinction, and improvement loop in tables and one diagram.
Final size: 1,155 prose words across two pages. Across the section, the senior editorial pass reduced prose from about 14,600 to 7,649 words while preserving verified behavior and security caveats.
Foundation
Shared navigation, route placeholders, Early Access badge support, and guide migrations are merged in #537. This PR now contains only its feature-owned files and passes CI independently.
Validation
npm run typecheck: passednpm run build: 377 pages built successfullyLatest source refresh
Adds Cancelled/Stop semantics, top-level-run work-item creation, and a link to the Control room for Activity operations.
Verified against Warp
e72fd7aacand warp-server9be39e484b. Broken, placeholder, partial, and spec-only surfaces remain excluded.Proposed reviewers
Based on the Warp Factories Soft Launch (August 18th) tracker. For planning only; no review requests have been sent.
@johnturcoo@peicodes@vorporealScreenshots
Not included. The revision uses sourced tables, Mermaid diagrams, and verified code/config examples; no safe approved Factory UI assets exist yet.
Unverified claims
None — all UI labels, defaults, eligibility claims, diagrams, and configuration details were verified against source or deliberately omitted.